<?xml version="1.0" encoding="UTF-8"?>
<html>
    <head>
        <link type="text/css" rel="stylesheet" href="./css/template.css" />
        <link type="text/css" rel="stylesheet" href="./css/SyntaxHighlighter.css" />
        <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
        <title>Cactus, tests unitaires sur des Servlet</title>
        <script language="javascript" src="./js/shInit.js" />
        <script language="javascript" src="./js/shCore.js" />
        <script language="javascript" src="./js/shBrushCpp.js" />
        <script language="javascript" src="./js/shBrushCSharp.js" />
        <script language="javascript" src="./js/shBrushCss.js" />
        <script language="javascript" src="./js/shBrushDelphi.js" />
        <script language="javascript" src="./js/shBrushJava.js" />
        <script language="javascript" src="./js/shBrushJScript.js" />
        <script language="javascript" src="./js/shBrushPhp.js" />
        <script language="javascript" src="./js/shBrushPython.js" />
        <script language="javascript" src="./js/shBrushRuby.js" />
        <script language="javascript" src="./js/shBrushSql.js" />
        <script language="javascript" src="./js/shBrushVb.js" />
        <script language="javascript" src="./js/shBrushXml.js" />
        <keywords>Cactus, Java, Tomcat</keywords>
        <author>Terry PRUDENT</author>
        <keywords />
    </head>
    <body>
        <div class="chapter">
            <h2>1. Introduction</h2>
            <p>
                During a project realisation, one will find plenty of essential steps including invariably one or more testing phases. However, some problems may appear considering J2EE component.
                <br />
                Indeed, J2EE is a complex environment. It includes component that execute themselves only in some particular environment, such as EJB or Servelts. Thus, this special environment behaves like a container that manages many services executed by the component. In such a context, it may take a long time to test the application.
                One possible solution would be to make this test inside a J2EE container. In this case, it would be necessary to have an interface allowing to call the component directly on server side. It's part of Cactus' work, giving you tools to test components on server side.
            </p>
        </div>
        <div class="chapter">
            <h2>2.Presentation</h2>
            <div class="subChapter">
                <h3>2.1.Cactus project</h3>
                <p>
                Cactus project is born from the will to provide developers simple and reliable tools. From this idea is born a testing framework, which goal is to cover at least every J2EE component models, and why not other types of component.
                    Cactus framework facilitates testing on pieces of code executed trough a server such as servlets or Enterprise Java Beans (EJB), thus reducing the time spent on testing, and it's cost. For this, Cactus uses JUnit, a testing framework famous among Extreme Programming developer, and from which it extends.
                    In order to realise these test, Cactus implements a strategy based on container, which means the tests are done inside these container.</p>
            </div>
            <div class="subChapter">
                <h3>2.2.Cactus ecosystem</h3>
                <p>
                    Cactus ecosystem is composed of several elements distributed with cactus. They will help you setting up the Cactus framework and give you examples on how to use it.
                    <br />
                    * Cactus framework, of course, which contains all the testing API.
                    <br />
                    * Cactus integration modules, which allows you using Cactus framework on different development environment simply. 
                    <br />
                    * Cactus samples, several simple projects showing how to write a cactus test or how to use some integration modules. 
                </p>
            </div>
        </div>
        <div class="chapter">
            <h2>3.Cactus "Installation"</h2>
            <div class="subChapter">
                <h3>3.1.Foreword</h3>
                <p>Considering Cactus is above all a framework, there is no real way of "installing" Cactus. There rather are several way to integrate it in your development environment. For this purpose, several integration modules depending on your environment exists. In this article, we'll consider Cactus implementation in a Tomcat environment.</p>
            </div>
            <div class="subChapter">
                <h3>3.2.Prerequisites</h3>
                <p>
                    You will need to have the fallowing elements installed on your computer in order to make Cactus test : 
                    <br />
                    * Java Virtual Machine (JVM) on version 1.2 or greater. It's also a prerequisites of servlet usage.
                    <br />
                    * A J2EE Servlet container. In order to launch local Cactus test, Servlet 2.X / J2EE 1.x must be installed on the computer.
                </p>
            </div>
            <div class="subChapter">
                <h3>3.3.Cactus file composition</h3>
                <p>
                    Cactus is composed of many JAR files essential for Cactus tests : 
                    <br />
                    * cactus.jar : The main JAR file, containing every single class of the framework. 
                    <br />
                    * httpclient.jar : This JAR is important as Cactus relies mainly on Jakarta Commons HttpClient framework for Cookies management. 
                    <br />
                    * commons-logging.jar :
                    <br />
                    * junit.jar : As we've already seen, Cactus uses JUnit and that's why this JAR is needed to use Cactus classes. 
                    <br />
                    * aspectjrt.jar : As Cactus uses AspectJ in some tasks, this JAR is as important as the preceding ones. 
                </p>
                <p>
                    These files are the strict minimum needed for the tests. However, JAR files with more precise roles are available :
                    <br />
                    * cactus-ant.jar : Eases the framework integration through Ant tasks included in the JAR. 
                    <br />
                    * servletapi.jar : This JAR file is needed for projects based on servlets. 
                    <br />
                    * httpunit.jar
                    <br />
                    * nekohtml.jar : Required for projects using httpUnit. 
                </p>
            </div>
            <div class="subChapter">
                <h3>3.4.Setting up the framework with Tomcat</h3>
                <p>Each environment you want to integrate the Cactus framework in has it's own integration method. Most of them are simple. I will present the Tomcat integration method in the following lines. You can however found all the integration modules on this page.</p>
                <h4>3.4.1.Tomcat and Cactus files</h4>
                <p>You first have to verify your Tomcat version is 4.0 or greater. In Tomcat install directory, you should find a ‘/common’ directory, himself containing a ‘/lib’ directory. It is in this directory that you will have to copy the Cactus JAR files.
                    Have we have seen before, you will at least need the cactus.jar, httpclient.jar, commons-logging.jar, junit.jar and aspectj.jar files to make Cactus test. They will thus need to be placed in the ‘/common/lib’ directory of the Tomcat install directory.</p>
                <h4>3.4.2.Modifying web.xml file from Tomcat</h4>
                <p>
                    You now have to modify the web.xml file, located in the ‘/conf’ directory of Tomcat install directory. You will have to add the following lines at the file beginning, just after the ‘<webapp>’ element. Make this modification carefully. To avoid any mistake, it is even counsel to backup the former web.xml file in case of an error during the modification : 
                </p>
                <textarea name="code" class="xml">
                    <servlet>
                        <servlet-name>ServletRedirector</servlet-name>
                        <servlet-class>org.apache.cactus.server.ServletTestRedirector</servlet-class>
                        <init-param>
                            <param-name>param1</param-name>
                            <param-value>value1 used for testing</param-value>
                        </init-param>
                    </servlet>
                    <servlet>
                        <servlet-name>ServletTestRunner</servlet-name>
                        <servlet-class>org.apache.cactus.server.runner.ServletTestRunner</servlet-class>
                    </servlet>
                </textarea>
                <p>
                    A second element has to be added in this file, after the last ‘<servlet>’ definition. Add the following lines :
                </p>
                <textarea name="code" class="xml">
                    <servlet-mapping>
                        <servlet-name>ServletRedirector</servlet-name>
                        <url-pattern>/ServletRedirector</url-pattern>
                    </servlet-mapping>
                    <servlet-mapping>
                        <servlet-name>ServletTestRunner</servlet-name>
                        <url-pattern>/ServletTestRunner</url-pattern>
                    </servlet-mapping>
                </textarea>
                <p>You can now save the modification made on your web.xml file. Your environment is then ready to make tests using the Cactus framework.</p>
            </div>
        </div>
        <div class="chapter">
            <h2>4.Making a test using Cactus</h2>
            <div class="subChapter">
                <h3>4.1.Writing a servlet test</h3>
                <p>
                    Writing a Cactus test consists of several steps. In the following lines, I will present some of the methods allowing you to test a code using objects from the Servlet API. You can find all of these steps as well as additional information on Cactus methods at this <a href="http://jakarta.apache.org/cactus/writing/howto_testcase.html" target="”_blank”">address</a>.
                </p>
                <p>
                    - The first step to realise your test is to import the ‘org.apache.cactus’ and ‘junit.framework’ packages. The first package contains logically Cactus classes, whereas the second one is a dependency used by Cactus as ‘client’ that calls the application tests. You should then have the following lines :
                    <textarea name="code" class="java">
                        import org.apache.cactus.*;
                        <br />
                        import junit.framework.*;
                    </textarea>
                </p>
                <p>
                - For the second step, you will create a class for testing purpose, that extends from one of cactus testing class. There are several testing class which can be used to test different objects types.</p>
                <p>
                In order to test a code using the Servlet API such as HttpServletRequest, HttpServletResponse, ServletConfig, etc... you have to create a class that extends from ServletTestCase.</p>
                <textarea name="code" class="java">public class MyTestServlet extends ServletTestCase
					{
					...
					}</textarea>
                <p>
                Following the same principle, you can create classes that tests codes using JSP API objects by extending the JspTestCase class, as well as extending from FilterTestCase class will allow you testing code using the Filter API. You also have the possibility to reuse a class extending from TestCase in the JUnit API by using the ServletTestSuite class.</p>
                <p>
                    - The last step consist of using the testXXX() method from your test class. This method is similar to the JUnit method named the same, but which has the particularity to execute itself inside a container. In this class, you will reuse the following operations :
                    <br />
                    * Instantiate the class you wish to test. 
                    <br />
                    * Setting up the objects server side (such as adding a variable in a http session). 
                    <br />
                    * Call the method to test. 
                    <br />
                    * Make the standard JUnit assertion using the assert(...), assertEqual(...) and fail(...) methods in order to verify the test success. 
                </p>
                <p>
                There also are optional methods you can chose to use or not. Thus, beginXXX(...) will allow you to initialise the http parameters. These parameters will then be accessible with testXXX(...) method. Similarly, endXXX(...) will be used to get the value of an http parameter sent back by the test such as a cookie or an http answer.</p>
            </div>
            <div class="subChapter">
                <h3>4.2.Example</h3>
                Here's a Cactus test example we can find on Jakarta project website : 
                <br />
                The class to test : 
                <textarea name="code" class="java">import javax.servlet.http.HttpServlet;
					import javax.servlet.http.HttpServletRequest;
					public class SampleServlet extends HttpServlet
					{
					public void saveToSession(HttpServletRequest request)
					{
					String testparam = request.getParameter("testparam");
					request.getSession().setAttribute("testAttribute", testparam);
					}
					}</textarea>
                <p>The testing class</p>
                <textarea name="code" class="java">public class TestSampleServlet extends ServletTestCase
					{
					public TestSampleServlet(String theName)
					{
					super(theName);
					}
					public static Test suite()
					{
					return new TestSuite(TestSampleServlet.class);
					}
					public void beginSaveToSessionOK(WebRequest webRequest)
					{
					webRequest.addParameter("testparam", "it works!");
					}
					public void testSaveToSessionOK()
					{
					SampleServlet servlet = new SampleServlet();
					servlet.saveToSession(request);
					assertEquals("it works!", session.getAttribute("testAttribute"));
					}
					}</textarea>
            </div>
            <div class="subChapter">
                <h3>4.3.Launching the test</h3>
                <p>
                    In order to execute the test, you must deploy it on the server, in the same way as an application. That means you must create your application directory architecture and have to put the .class files of your test class and application to test in the ‘WEB-INF/classes’ directory. Once it's done, you will be able to test your application by opening a window of your web browser at this <a href="http://localhost:8080/dossier_mon_application/ServletTestRunner?suite=class_de_test" target="”_blank”">address</a>.

					The test result will be shown as an XML files which should look like the following : 
                </p>
                <textarea name="code" class="xml">
                    &lt;?xml version=”1.0” encoding=”UTF-8” ?&gt;
                    <testsuites>
                        <testsuite name="”class_de_test”" tests="”1”" failures="”0”" errors="”0”" time="”0.27”">
                            <testcase name="”methode_a_tester”" time="”0.2”" />
                        </testsuite>
                    </testsuites>
                </textarea>
                <p>
                    Another view of the test information presented as a data table exists. For that, you will have to download the XSLT style sheet and put it in your application directory. You will then have to make your test using this <a href="http://localhost:8080/dossier_mon_application/ServletTestRunner?suite=class_de_test&amp;xls=cactus-report.xsl" target="”_blank”">address</a>.
                </p>
            </div>
        </div>
        <div class="chapter">
            <h2>5.Conclusion</h2>
            <p>This article presented you the Cactus framework, which particularity is to offer you several tools to test server side component inside container. As explain by the Cactus development team, more and more component are developed, and container offer more and more services linked to these component. Thus, it's important that such projects are developed in order to ease the components test and help the developer to better concentrate on the application development while being sure that their application works fine once deployed.</p>
        </div>
        <div class="chapter">
            <h2>6.Information sources</h2>
            <p>
                Most information presented here were collected on the jakarta project website. You can visit it at this <a href="http://jakarta.apache.org/cactus/" target="”_blank”">address</a>.
            </p>
        </div>
    </body>
</html>

